home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 46 / Amiga Format CD46 (1999-10-20)(Future Publishing)(GB)[!][issue 1999-12].iso / -in_the_mag- / reader_requests / codecs / developer / doc / codecs.doc
Text File  |  1999-09-16  |  6KB  |  194 lines
  1. TABLE OF CONTENTS
  2.  
  3. codecs.library/--general--
  4. codecs.library/NewCodec
  5. codecs.library/DisposeCodec
  6. codecs.library/Encode
  7. codecs.library/Decode
  8. codecs.library/--tags--
  9.  
  10. codecs.library/--general--                           codecs.library/--general--
  11.  
  12.     codecs.library is designed to manage implementations of various compression
  13.     codecs and to provide a uniform interface to all these codecs.
  14.     The functions in the codecs.library create and destroy codec objects and
  15.     provide a common interface for all codecs.
  16.  
  17.     A codec class is in fact a BOOPSI class stored in a shared library file.
  18.     The codecs.library opens this file for you when a codec object is created.
  19.     Instead of using the intuition DoMethod() function to invode the object's
  20.     methods, the codecs.library provides an Encode() and Decode() function to
  21.     handle the compression.
  22.  
  23. codecs.library/NewCodec                                 codecs.library/NewCodec
  24.  
  25.     NAME
  26.         NewCodec - Create a new codec object
  27.  
  28.     SYNOPSIS
  29.         Codec = NewCodec(CodecName, Version)
  30.         D0               A0         D0
  31.  
  32.         Codec *NewCodec(char *, ULONG)
  33.  
  34.     FUNCTION
  35.         This is the general method of creating codec objects from 'codec'
  36.         classes. 
  37.  
  38.     INPUT
  39.         CodecName - The name of the codec class to create an instance of,
  40.                     for example "byterun.codec" creates a codec object of
  41.                     class byterun.codec.
  42.         Version   - Minimum version of the codec class.
  43.  
  44.     RESULT
  45.         Codec     - Pointer to created codec object or 0 when an error
  46.                     occured.
  47.  
  48.     SEE ALSO
  49.         DisposeCodec()
  50.  
  51. codecs.library/DisposeCodec                         codecs.library/DisposeCodec
  52.  
  53.     NAME
  54.         DisposeCodec - Dispose a codec object
  55.  
  56.     SYNOPSIS
  57.         DisposeCodec(Codec)
  58.                      A0
  59.  
  60.         DisposeCodec(Codec *)
  61.  
  62.     FUNCTION
  63.         Dispose a codec object
  64.  
  65.     INPUT
  66.         Codec     - Pointer to a previously created codec object
  67.  
  68.     SEE ALSO
  69.         NewCodec()
  70.  
  71.  
  72. codecs.library/Encode                                     codecs.library/Encode
  73.  
  74.     NAME
  75.         Encode - Encode a source using the codec object
  76.  
  77.     SYNOPSIS
  78.         Result = Encode(Codec, TagItems)
  79.         D0              A0     A1
  80.  
  81.         LONG Encode(Codec *, struct TagItem *)
  82.  
  83.     FUNCTION
  84.         Dispose a codec object
  85.  
  86.     INPUT
  87.         Codec     - Pointer to a previously created codec object
  88.  
  89.         TagItems  - Array of TagItem structures, terminated by the value
  90.                     TAG_END. This must contain a source and destination tag.
  91.  
  92.     RESULT
  93.         Result    - The number of bytes written to the destination or an error
  94.                     value. Error values are always negative.
  95.  
  96.     SEE ALSO
  97.         Decode()
  98.  
  99. codecs.library/Decode                                     codecs.library/Decode
  100.  
  101.     NAME
  102.         Decode - Decode a source using the codec
  103.  
  104.     SYNOPSIS
  105.         Result = Decode(Codec, TagItems)
  106.         D0              A0     A1
  107.  
  108.         LONG Decode(Codec *, struct TagItem *)
  109.  
  110.     FUNCTION
  111.         Decode the source to destination using the specified codec object.
  112.         The source must be a memory
  113.  
  114.     INPUT
  115.         Codec     - Pointer to a previously created codec object
  116.  
  117.         TagItems  - Array of TagItem structures, terminated by the value
  118.                     TAG_END. This must contain a source and destination tag.
  119.  
  120.     RESULT
  121.         Result    - The number of bytes used from the source the decode the
  122.                     picture from or an error value. Error values are always
  123.                     negative.
  124.  
  125.     SEE ALSO
  126.         Encode()
  127.  
  128.  
  129. codecs.library/--tags--                                 codecs.library/--tags--
  130.  
  131.     THE TAGS FOR Encode() AND Decode()
  132.  
  133.     GENERAL
  134.  
  135.     SOURCE TAGS
  136.  
  137.       CA_DST_HANDLE
  138.         This tag specifies the destination for the encoded or decoded data.
  139.         The type of the handle determines whether additional attributes for
  140.         the destination handle.
  141.  
  142.       CA_DST_TYPE
  143.         This tag specifies the type of destination handle. Depending on the
  144.         type additional tags are:
  145.  
  146.         - TYPE_MEMORY  Destination is a buffer in memory.
  147.         - TYPE_BITMAP  Destination is a standard BitMap structure as defined
  148.                        in gfx.h.
  149.  
  150.       CA_DST_SIZE
  151.         This tag specifies the size of the destination buffer when the
  152.         destination is of type TYPE_MEMORY.
  153.  
  154.     DESTINATION TAGS
  155.  
  156.       CA_SRC_HANDLE
  157.         This tag specifies the source for the encoded or decoded data. The
  158.         type of the handle determines whether additional attributes for
  159.         the source handle.
  160.  
  161.       CA_SRC_TYPE
  162.         This tag specifies the type of source handle. Depending on the
  163.         type additional tags are:
  164.  
  165.         - TYPE_MEMORY  Source is a buffer in memory.
  166.         - TYPE_BITMAP  Source is a standard BitMap structure as defined
  167.                        in gfx.h.
  168.  
  169.       CA_SRC_SIZE
  170.         This tag specifies the size of the source buffer when the source
  171.         is of type TYPE_MEMORY.
  172.  
  173.     IMAGE TAGS
  174.  
  175.       CA_IMAGEWIDTH
  176.       CA_IMAGEHEIGHT
  177.       CA_IMAGEDEPTH
  178.         These tags specify the width of height and depth of an image when one
  179.         of source destination handles is of type TYPE_BITMAP. Default these
  180.         values are taken from the BitMap structure itself, but you may set
  181.         them yourself with these tags. Especially the image width because
  182.         that is inaccurate because it is taken from BytesPerRow which may
  183.         indicate a larger value than you image really has.
  184.  
  185.     TODO
  186.  
  187.     More tags will be defined when there are codecs that:
  188.  
  189.     - decode images progressively
  190.     - perform lossy coding for images
  191.     - code animations
  192.     - offer a choice for different entropy coders
  193.     - etc..
  194.